Tokens at the IXC ACS

Introduction

The IXC ACS authentication is based on JWTs (JSON Web Tokens), a self-contained form of token that loads on your payload a JavaScript object and a digital signature. The JWTs used in ACS are signed using ECDSA (Elliptic Curve Digital Signature Algorithm) keys.

Before using the IXCsoft ACS API JWTs, it is crucial to understand its operation and generate its ECDSA key pair.

Structure of a JWT

A JWT consists of three main parts:

1. ** Head*: Contains information on the type of signature used in Token.
2. Bodies: Stores data related to Token's creator user, its recipient and Token's own information.
3. Signature: It contains a digital signature of the two previous parts of the Token.

The default format of a JWT is:

xxxxxx.yyyyyy.zzzzzz

Where: -xxxxxx: Basecoded Header64Url -yyyyyy: Body encoded in Base64Url -zzzzzz: Signature coded in Base64Url

Never transmit sensitive data on a JWT. The information in JWT's body is only encrypted, not encrypted. In unsafe connections, consider your JWT unprotected.

I'll be right there # Detailing of JWT Parts

Header

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9

* ```json
{
  "alg": "ES256",
  "typ": "JWT"
}

-typ: Indicates that the document is of type JWT. -alg: Specifies the cryptographic algorithm used in the signature (always ES256 for Tokens of the IXC ACS API). Body

eyJpc3MiOiI2MTg1ODMyNGRlNmNlZjAwMTFmNTFiMDUiLCJleHAiOjE2MzgyMTU3MDgsImlhdCI6MTYzODIxNDcwOH0

* ```json
{
  "iss": "61858324de6cef0011f51b05",
  "exp": 1638215708,
  "iat": 1638214708
}

-iss: JWT Emitter Identifier (Client API ID). -exp: Token expiration timestamp UNIX. -iat: Token creation timestamp UNIX.

A short period of validity for the Authorization Token is recommended to reduce risks of misuse.

Signature

F1DRaeJcQ1oG8Nc33R0iSEBppEGFUQmLFKDzAaX3e9I2sTLZT0qOerw8nUhbcogAZsZpwQdQdAnU4B0SKIvBDA

The signature is automatically generated using the private key of the Token emitter.
# Process of Creation and Use of Token
1. Add the necessary data to Token's body.
2. Sign Token using the ES256 algorithm and its Private Key.
3. Use the generated Token to request an Access Token.
4. Send Token as Bearer Token to the API Authentication Endpoint.
# Security considerations
- What? Keep your private keys safe.
- Use HTTPS for all communications involving JWTs.
- What? Implement regular key rotation to increase security.
# Read it too
- [Preset no ACS](./preset%20no%20acs)
- [Projetos ACS](../projetos%20acs)
- [Protocolo TR-069](./protocolo%20tr-069)